home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / yawindow.arc / YAWINDOW.DOC < prev    next >
Encoding:
Text File  |  1986-01-30  |  9.4 KB  |  373 lines
  1. Prologue
  2. --------
  3.  
  4.     There's a lot of window'ish packages around.  So, i'll dub this one
  5.     Yet Another Windows, or YAW for short.
  6.  
  7.     I find it very difficult to work for free.  But feel that these
  8.     functions could be quite usefull to many others.  So, a compromise,
  9.     you may use this partial library in any of your programs.  But, for
  10.     the source, I request a minimal fee.  And copyrights, well i'll
  11.     retain these.
  12.  
  13.     For those without source code, you must use w_co(), w_putchar() and
  14.     w_puts() for character output. And you may find it difficult to make
  15.     your printf operate under these windows.
  16.  
  17.     This library and documentation is for those without the source
  18.     code, and is incomplete.
  19.  
  20.     These funcions operate on the PC color graphics card, the monochrome
  21.     card or their equivalents. Recognition of card type is automatic.
  22.  
  23.     The acceptable video modes are co80 and bw80.  If video is not in
  24.     either of these modes, it will be set to co80.
  25.  
  26.     The special window w_screen maps the physical screen.  When no
  27.     windows are open this is the output device.  It behaves just like a
  28.     normal screen.  But as the current device it can be operated on as
  29.     a window execept it must not be closed, moved or located.  It's
  30.     attributes can be changed for special effects.
  31.  
  32.     These functions and globals are prefixed by s_ or w_.  The s_
  33.     objects deal with the physical screen, and their functions are
  34.     written in assembly.  The w_ objects handle logic level windowing
  35.     and the functions are written in C.
  36.  
  37.     The following describes the functions and globals you may use in
  38.     your programs.
  39.  
  40.     Format this as you please.
  41.  
  42.  
  43.  
  44. The Globals
  45. -----------
  46.  
  47. char s_attr
  48.  
  49.     s_attr is the color of all output.
  50.  
  51. unsigned s_curtype
  52.  
  53.     s_curtype is the default cursor type.  It's value is a PC cursor
  54.     type code.
  55.  
  56. char s_curstat
  57.  
  58.     s_curstat is true if the cursor and should be moved.
  59.  
  60. char (*w_open_frame)[]
  61.  
  62.     w_open_frame points to a character array containing the character
  63.     set to be used for a window's frame when the window is opened.  If
  64.     zero no frame surrounds the window.
  65.  
  66. char (*w_explode_frame)[]
  67.  
  68.     w_explode_frame points to the character set to be used for
  69.     explosions.  If zero no explosions occur.
  70.  
  71. char w_attr_frame
  72.  
  73.     Color used for open frames and explosions.
  74.  
  75.  
  76. char w_single_frame[], w_double_frame[], w_mix_frame[], w_bold_frame[]
  77.  
  78.     A couple of frame character sets.
  79.  
  80.  
  81. int w_exp_delay
  82.  
  83.     Delay constant used to control explosion speed.
  84.  
  85. int w_exp_frame
  86.  
  87.     Count of frames per explosion.
  88.  
  89.  
  90. The Functions
  91. -------------
  92.  
  93. typedef struct window *WP ;        /* the handle is pointer to struct */
  94.  
  95.  
  96. w_setup()
  97.  
  98.     synopsis:    void w_setup()
  99.  
  100.     example:    w_setup() ;
  101.  
  102.     Must be called before any other w_ or s_ call is made.  Make this
  103.     your first call in main.  This function determins what type of
  104.     video board is in use, color or mono, assures the mode is bw80 or
  105.     co80.  And also replaces the DOS critical error handler, with a
  106.     windowed version.
  107.  
  108.  
  109. w_open()
  110.  
  111.     synopsis:    WP w_open( top_row, top_col, bottom_row, bottom_col )
  112.                 int top_row, top_col, bottom_row, bottom_col ;
  113.  
  114.     example:    WP w1 ;
  115.                 w1 = w_open( 5, 5, 10, 10 ) ;
  116.  
  117.     w_open() will open a window as the active consol output device. 
  118.     It's arguments define the area of the screen to be used by the
  119.     window.  The arguments are row of top left corner of window, column
  120.     of top left corner, row of bottom right corner and column of bottom
  121.     right corner.  It returns a handle which must be used to identify
  122.     this window to other functions.  Or it returns 0 when out of free
  123.     memory.  If sucessfull, the window explodes on the screen.
  124.     The default values s_attr, s_curtype and s_curstat are copied to
  125.     the window.  The area within the frame will be blanked.  And the
  126.     cursor will be positioned in the top left corner within the frame. 
  127.     Note well, there is no error check for bad arguments.  A call with
  128.     arguments out of order or bounds produces unknown results.  There
  129.     is no other limit on the number of windows concurrently open.
  130.  
  131.     eg.
  132.         s_attr = 10 ;                /* set the windows color now */
  133.         s_curtype = 0x0607 ;        /* it's cursor type */
  134.         s_curstat = 1 ;                /* cursor should be on */
  135.         w = w_open( 10, 20, 20, 60 ) ;    /* open it */
  136.  
  137.     Note the usage of globals as above, allows simpler calling
  138.     conventions.  Programming is thus easier, except when multiple
  139.     coloring or cursor changes occur.  Which is not that often.
  140.  
  141.  
  142. w_title()
  143.  
  144.     synopsis:    void w_title( string )
  145.                     char *string ;
  146.  
  147.     example:    w_title( "[ TITLE ]" ) ;
  148.  
  149.     w_title() will center a title string on the current window's top frame
  150.     border. It's color is the default color. Commomly called just after a
  151.     w_open().
  152.  
  153.  
  154. w_close()
  155.  
  156.     synopsis:    void w_close( w )
  157.                     WP w ;
  158.  
  159.     example:    WP w1 ;
  160.                 w_close( w1 ) ;
  161.  
  162.  
  163.     w_close() will remove a window from the screen, and free the memory
  164.     used by it.  If the window is the current output window, the
  165.     previous output window will be activated.  No output to this window
  166.     should follow.
  167.  
  168.  
  169. w_closeall()
  170.  
  171.     synopsis:    void w_closeall()
  172.  
  173.     example:    w_closeall() ;
  174.  
  175.     w_closeall() will close all windows currently open.
  176.  
  177.  
  178. w_active() 
  179.  
  180.     synopsis:    void w_active( w )
  181.                     WP w ;
  182.  
  183.     example:    WP w1 ;
  184.                 w_active( w1 ) ;
  185.  
  186.     w_active() will make the specified window the current window.  If
  187.     this window is covered by other windows, it will be uncovered.  The
  188.     default color will be set to this windows default.  The cursor, if
  189.     on in this window will be turned on, and will be positioned to the
  190.     current location in this window.
  191.  
  192.  
  193. w_locate()
  194.  
  195.     synopsis:    void w_locate( row, col )
  196.                     int row, col ;
  197.  
  198.     example:    w_locate( 10, 30 ) ;
  199.  
  200.  
  201.     w_locate() will relocate the entire current window.  It's arguments
  202.     are the new upper left corner row and column coordinates.  No
  203.     boundary checks are made.  Out of bound moves produce unknown
  204.     result.
  205.  
  206.  
  207. w_move()
  208.  
  209.     synopsis:    void w_move( dir )
  210.                     int dir ;
  211.  
  212.     example:    w_move( 1 ) ;
  213.  
  214.     w_move() will move the current window one character space in the
  215.     specified direction.  The directions are :
  216.  
  217.                 1                    1    up
  218.               4 X 2                    2     right
  219.                 3                    3    down
  220.                                     4    left
  221.  
  222.     Only arguments of 1 through 4 valid.  The function does a boundary
  223.     check so that only movements within the screen ( w_screen ) are
  224.     performed.  Out of bounds movements are ignored.
  225.     
  226.  
  227.  
  228.  
  229.  
  230.  
  231. Functions which Operate on a Window's Workspace
  232. -----------------------------------------------
  233.     The workspace of a window is the area within the windows frame.
  234.  
  235.  
  236. w_cursoff()
  237.  
  238.     synopsis:    void w_cursoff()
  239.  
  240.     w_cursoff() will turn the cursor off in the current window only.
  241.  
  242.  
  243. w_curson()
  244.  
  245.     synopsis:    void w_curson()
  246.  
  247.     w_curson() will restore the current window's cursor.
  248.  
  249.  
  250. w_rowcol()
  251.  
  252.     synopsis:    void w_rowcol( row, col )
  253.                     int row, col ;
  254.  
  255.     example:    w_rowcol( 2, 1 ) ;
  256.  
  257.     w_rowcol() will position the cursor within the current window.  The
  258.     top left corner of the window's workspace is 0, 0 .  No boundary
  259.     checks are performed.
  260.  
  261.  
  262. w_getrowcol()
  263.  
  264.     synopsis:    void w_getrowcol( prow, pcol )
  265.                     int *prow, *pcol ;
  266.  
  267.     example:    int r, c ;
  268.                 w_getrowcol( &r, &c ) ;
  269.  
  270.     w_getrowcol() reads the current window's cursor position. It assumes
  271.     0, 0 is the top left corner of the current window's workspace.
  272.  
  273.  
  274. w_clr()
  275.  
  276.     synopsis:    void w_clr()
  277.  
  278.     w_clr() will clear the current window's workspace and position the
  279.     cursor to the top left corner.
  280.  
  281.  
  282. w_color()
  283.  
  284.     synopsis:    void w_color( attr )
  285.                     char attr ;
  286.  
  287.     example:    w_color( 7 ) ;
  288.  
  289.     w_color() will color the entire current window's workspace.  No
  290.     characters are changed only attributes.  The color becomes this
  291.     window's default color.  It's argument is a PC color code.
  292.  
  293.  
  294. w_co()
  295.  
  296.     synopsis:    void w_co( c ) 
  297.                     char c ;
  298.  
  299.     example:    w_co( 'A' ) ;
  300.  
  301.     w_co() is simular to your old co().  Except character output is
  302.     confined to the current window's workspace and all characters are
  303.     s_attr in color.  Output can not be redirected.
  304.  
  305.  
  306. w_putchar()
  307.  
  308.     synopsis:    void w_putchar( c )
  309.                     char c ;
  310.  
  311.     example:    w_putchar( '\n' ) ;
  312.  
  313.     w_putchar() is likewise simular to putchar().  Except output is
  314.     through w_co() and thus restritced to the current window.
  315.  
  316.  
  317. w_puts()
  318.  
  319.     synopsis:    void w_puts( s )
  320.                     char *s ;
  321.  
  322.     example:    w_puts( "hello world" ) ;
  323.  
  324.     w_puts() is again simular to puts().  Except output is through
  325.     w_putchar() and is so restricted.
  326.  
  327.  
  328. w_center()
  329.  
  330.     synopsis:    void w_center( s )
  331.                     char *s ;
  332.  
  333.     example:    w_center( "hello world" ) ;
  334.  
  335.     w_center() will center the string in the current window on the
  336.     current line.
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343. Others
  344. ------
  345.  
  346. w_error()
  347.  
  348.     synopsis:    void w_error( actions, message1, message2 )
  349.                     int actions ;
  350.                     char *message1, message2 ;
  351.  
  352.     example:    w_error( ERR_ARI, "Can't Open File", "CUSTOMERS.DAT" ) ;
  353.  
  354.     w_error() is a "general purpose error message handler".  It pops a
  355.     window and displays the first message string, and a second message
  356.     ( if message2 is non zero ).  The actions of ABORT, RETRY and
  357.     IGNORE are available, and are specified by the parameter actions. 
  358.     This function is also used by the DOS critical error handler
  359.     replacement.
  360.  
  361.  
  362.  
  363. Epilogue
  364. --------
  365.  
  366.     I stripped these functions out of a data base written long ago 
  367.     ('83 ).  So, if memory serves me well, the above is enough to get
  368.     you by.  But should you find i've left something out or be in
  369.     error, i'm sure you'll let me know.
  370.  
  371.                                         Enjoy it. ( while you can )
  372.                                                 Mark Feeney.
  373.